[Question] How do I mark a command as deprecated?

[ryandberger]

I see from #1559 that it is now possible to mark options as deprecated. I have attempted to use this functionality at a higher level to mark an entire command as deprecated, but it does not work. Is this feature not yet implemented or am I missing something?

This is the usage I am attempting:

module.exports = {
  command: 'old [path]',
  deprecated: '[deprecated: use new instead]'
};

[jly36963]

I believe #1559 only applies to options, whereas #1624 is for commands.

Example

You can use deprecated: true or deprecated: "explanation here" for both options and commands.

My example uses the yargs.command(module) syntax, but it should also work for yargs.command(cmd, description, builder, handler, commandMiddleware, deprecated).

const yargs = require("yargs");

let input

/*
input = '--help'  // you will see `[deprecated]` next to the command "cmd1"
input = 'cmd1 --help' // you will see `[deprecated]` next to the option "deprecated-arg"
*/

yargs(input)
  .command({
    command: 'cmd1',
    desc: 'cmd1 desc',
    builder: yargs => yargs
      .option('arg', {
        type: 'string',
        desc: 'arg desc',
      })
      .option('deprecated-arg', {
        type: 'string',
        desc: 'deprecated-arg desc',
        deprecated: true // deprecate option
        // deprecated: 'use "arg" option instead' // deprecate option (with explanation)
      }),
    handler: argv => {
      console.log(argv)
    },
    deprecated: true // deprecate command
    // deprecated: 'use "cmd2" command instead' // deprecate command (with explanation)
  })
  .command({
    command: 'cmd2',
    desc: 'cmd2 desc',
    builder: yargs => yargs
      .option('arg', {
        type: 'string',
        desc: 'arg desc',
      }),
    handler: argv => {
      console.log(argv)
    },
  })
  .strict()
  .parse()

Does this answer your question?

[ryandberger]

Yes, I do see the [deprecated] indicator next to command cmd1 when calling --help generally. But when I call cmd1 --help I don't see the message after the command description which I think is unexpected.

[jly36963]

@ryandberger
I agree, I think it would be helpful to include it there.

My personal opinion is that it would also be nice if a warning was emitted during validation for any deprecated commands/options used. Maybe that solution is too heavy-handed, but I think there are a few ways to make it reasonable:

• deprecated can currently be a boolean or string. I could change the logic to allow for an object
  • eg. { reason: 'use other command instead', emitWarning: true }
• add a key like emit-deprecation-warnings to the yargs configuration, and let the developer control it.
• make an emitted warning the default behavior, but wait until a major/minor release (because it's a pretty significant change).

I'll think on this and figure out a reasonable solution.

[ryandberger]

Would love to see a warning emitted when the command is used. I think that would be particularly useful for automation processes. For your approach, I personally would lean towards option 2 since I imagine developers would want consistent behavior across their app. I think it would also make option 3 more natural to implement when the time comes. Appreciate your help on this!

[ryandberger]

Related to this: I noticed that aliases attribute also only displays at the top level. Would be helpful to also see '[aliases]indicator display when callingcmd1 --help`. Figured it might be convenient to bundle the work together if you agree with my request.

[AgentEnder]

@shadowspawn do you know if this was ever decided on further? I'd love to have this, even if its something opt-in like with "yargs().showDeprecationMessages()" or similar.

[shadowspawn]

There have not been any further discussions about runtime warnings (that I have seen).

There are a couple of related issues on the help and docs: #2248 #2246